<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">











<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Math - The Commons Math User Guide - Linear Algebra</title>
    <style type="text/css" media="all">
      @import url("../css/maven-base.css");
      @import url("../css/maven-theme.css");
      @import url("../css/site.css");
    </style>
    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
      </head>
  <body class="composite">
    <div id="banner">
                    <span id="bannerLeft">
    
            Commons Math User Guide
    
            </span>
                    <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="breadcrumbs">
          
  

  
    
  
  
    
              <div class="xright">      
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
    <div id="leftColumn">
      <div id="navcolumn">
           
  

  
    
  
  
    
                   <h5>User Guide</h5>
            <ul>
              
    <li class="none">
                    <a href="../userguide/index.html">Contents</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/overview.html">Overview</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/stat.html">Statistics</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/random.html">Data Generation</a>
          </li>
              
    <li class="none">
              <strong>Linear Algebra</strong>
        </li>
              
    <li class="none">
                    <a href="../userguide/analysis.html">Numerical Analysis</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/special.html">Special Functions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/utilities.html">Utilities</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/complex.html">Complex Numbers</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/distribution.html">Distributions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/fraction.html">Fractions</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/transform.html">Transform Methods</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/geometry.html">3D Geometry</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/optimization.html">Optimization</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/ode.html">Ordinary Differential Equations</a>
          </li>
              
    <li class="none">
                    <a href="../userguide/genetics.html">Genetic Algorithms</a>
          </li>
          </ul>
                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
          </a>
                       
  

  
    
  
  
    
        </div>
    </div>
    <div id="bodyColumn">
      <div id="contentBox">
        <div class="section"><h2><a name="a3_Linear_Algebra"></a>
3 Linear Algebra</h2>
<div class="section"><h3><a name="a3.1_Overview"></a>
3.1 Overview</h3>
<p>
           Linear algebra support in commons-math provides operations on real matrices
           (both dense and sparse matrices are supported) and vectors. It features basic
           operations (addition, subtraction ...) and decomposition algorithms that can
           be used to solve linear systems either in exact sense and in least squares sense.
        </p>
</div>
<div class="section"><h3><a name="a3.2_Real_matrices"></a>
3.2 Real matrices</h3>
<p>
          The <a href="../apidocs/org/apache/commons/math/linear/RealMatrix.html">
          RealMatrix</a>
 interface represents a matrix with real numbers as 
          entries.  The following basic matrix operations are supported:
          <ul><li>Matrix addition, subtraction, multiplication</li>
<li>Scalar addition and multiplication</li>
<li>transpose</li>
<li>Norm and Trace</li>
<li>Operation on a vector</li>
</ul>
</p>
<p>
         Example:
         <div class="source"><pre>
// Create a real matrix with two rows and three columns
double[][] matrixData = { {1d,2d,3d}, {2d,5d,3d}};
RealMatrix m = new Array2DRowRealMatrix(matrixData);

// One more with three rows, two columns
double[][] matrixData2 = { {1d,2d}, {2d,5d}, {1d, 7d}};
RealMatrix n = new Array2DRowRealMatrix(matrixData2);

// Note: The constructor copies  the input double[][] array.

// Now multiply m by n
RealMatrix p = m.multiply(n);
System.out.println(p.getRowDimension());    // 2
System.out.println(p.getColumnDimension()); // 2

// Invert p, using LU decomposition
RealMatrix pInverse = new LUDecompositionImpl(p).getSolver().getInverse();
         </pre>
</div>
</p>
<p>
        The three main implementations of the interface are <a href="../apidocs/org/apache/commons/math/linear/Array2DRowRealMatrix.html">
        Array2DRowRealMatrix</a>
 and <a href="../apidocs/org/apache/commons/math/linear/BlockRealMatrix.html">
        BlockRealMatrix</a>
 for dense matrices (the second one being more suited to
        dimensions above 50 or 100) and <a href="../apidocs/org/apache/commons/math/linear/SparseRealMatrix.html">
        SparseRealMatrix</a>
 for sparse matrices.
        </p>
</div>
<div class="section"><h3><a name="a3.3_Real_vectors"></a>
3.3 Real vectors</h3>
<p>
          The <a href="../apidocs/org/apache/commons/math/linear/RealVector.html">
          RealVector</a>
 interface represents a vector with real numbers as 
          entries.  The following basic matrix operations are supported:
          <ul><li>Vector addition, subtraction</li>
<li>Element by element multiplication, division</li>
<li>Scalar addition, subtraction, multiplication, division and power</li>
<li>Mapping of mathematical functions (cos, sin ...)</li>
<li>Dot product, outer product</li>
<li>Distance and norm according to norms L1, L2 and Linf</li>
</ul>
</p>
<p>
          The <a href="../apidocs/org/apache/commons/math/linear/RealVectorFormat.html">
          RealVectorFormat</a>
 class handles input/output of vectors in a customizable
          textual format.
        </p>
</div>
<div class="section"><h3><a name="a3.4_Solving_linear_systems"></a>
3.4 Solving linear systems</h3>
<p>
          The <code>solve()</code> methods of the <a href="../apidocs/org/apache/commons/math/linear/DecompositionSolver.html">DecompositionSolver</a>

          interface support solving linear systems of equations of the form AX=B, either
          in linear sense or in least square sense. A <code>RealMatrix</code> instance is
          used to represent the coefficient matrix of the system. Solving the system is a
          two phases process: first the coefficient matrix is decomposed in some way and
          then a solver built from the decomposition solves the system. This allows to
          compute the decomposition and build the solver only once if several systems have
          to be solved with the same coefficient matrix.
        </p>
<p>
          For example, to solve the linear system
          <pre>
           2x + 3y - 2z = 1
           -x + 7y + 6x = -2
           4x - 3y - 5z = 1
          </pre>
          Start by decomposing the coefficient matrix A (in this case using LU decomposition)
          and build a solver
          <div class="source"><pre>
RealMatrix coefficients =
    new Array2DRowRealMatrix(new double[][] { { 2, 3, -2 }, { -1, 7, 6 }, { 4, -3, -5 } },
                       false);
DecompositionSolver solver = new LUDecompositionImpl(coefficients).getSolver();
          </pre>
</div>

          Next create a <code>RealVector</code> array to represent the constant
          vector B and use <code>solve(RealVector)</code> to solve the system
          <div class="source"><pre>
RealVector constants = new RealVectorImpl(new double[] { 1, -2, 1 }, false);
RealVector solution = solver.solve(constants);
          </pre>
</div>

          The <code>solution</code> vector will contain values for x
          (<code>solution.getEntry(0)</code>), y (<code>solution.getEntry(1)</code>), 
          and z (<code>solution.getEntry(2)</code>) that solve the system.
        </p>
<p>
          Each type of decomposition has its specific semantics and constraints on
          the coefficient matrix as shown in the following table. For algorithms that
          solve AX=B in least squares sense the value returned for X is such that the
          residual AX-B has minimal norm. If an exact solution exist (i.e. if for some
          X the residual AX-B is exactly 0), then this exact solution is also the solution
          in least square sense. This implies that algorithms suited for least squares
          problems can also be used to solve exact problems, but the reverse is not true. 
        </p>
<p><table class="bodyTable"><tr class="a"><td><font size="+2">Decomposition algorithms</font></td>
</tr>
<tr class="b"><font size="+1"><td>Name</td>
<td>coefficients matrix</td>
<td>problem type</td>
</font></tr>
<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/LUDecomposition.html">LU</a>
</td>
<td>square</td>
<td>exact solution only</td>
</tr>
<tr class="b"><td><a href="../apidocs/org/apache/commons/math/linear/CholeskyDecomposition.html">Cholesky</a>
</td>
<td>symmetric positive definite</td>
<td>exact solution only</td>
</tr>
<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/QRDecomposition.html">QR</a>
</td>
<td>any</td>
<td>least squares solution</td>
</tr>
<tr class="b"><td><a href="../apidocs/org/apache/commons/math/linear/EigenDecomposition.html">eigen decomposition</a>
</td>
<td>square</td>
<td>exact solution only</td>
</tr>
<tr class="a"><td><a href="../apidocs/org/apache/commons/math/linear/SingularValueDecomposition.html">SVD</a>
</td>
<td>any</td>
<td>least squares solution</td>
</tr>
</table>
</p>
<p>
          It is possible to use a simple array of double instead of a <code>RealVector</code>.
          In this case, the solution will be provided also as an array of double.
        </p>
<p>
          It is possible to solve multiple systems with the same coefficient matrix 
          in one method call.  To do this, create a matrix whose column vectors correspond 
          to the constant vectors for the systems to be solved and use <code>solve(RealMatrix),</code>
          which returns a matrix with column vectors representing the solutions.
        </p>
</div>
<div class="section"><h3><a name="a3.5_Eigenvalueseigenvectors_and_singular_valuessingular_vectors"></a>
3.5 Eigenvalues/eigenvectors and singular values/singular vectors</h3>
<p>
          Decomposition algorithms may be used for themselves and not only for linear system solving.
          This is of prime interest with eigen decomposition and singular value decomposition.
        </p>
<p>
          The <code>getEigenvalue()</code>, <code>getEigenvalues()</code>, <code>getEigenVector()</code>,
          <code>getV()</code>, <code>getD()</code> and <code>getVT()</code> methods of the
          <code>EigenDecomposition</code> interface support solving eigenproblems of the form
          AX = lambda X where lambda is a real scalar.
        </p>
<p>The <code>getSingularValues()</code>, <code>getU()</code>, <code>getS()</code> and
        <code>getV()</code> methods of the <code>SingularValueDecomposition</code> interface
        allow to solve singular values problems of the form AXi = lambda Yi where lambda is a
        real scalar, and where the Xi and Yi vectors form orthogonal bases of their respective
        vector spaces (which may have different dimensions).
        </p>
</div>
<div class="section"><h3><a name="a3.6_Non-real_fields_complex_fractions_..."></a>
3.6 Non-real fields (complex, fractions ...)</h3>
<p>
          In addition to the real field, matrices and vectors using non-real <a href="../apidocs/org/apache/commons/math/FieldElement.html">field elements</a>
 can be used.
          The fields already supported by the library are:
          <ul><li><a href="../apidocs/org/apache/commons/math/complex/Complex.html">Complex</a>
</li>
<li><a href="../apidocs/org/apache/commons/math/fraction/Fraction.html">Fraction</a>
</li>
<li><a href="../apidocs/org/apache/commons/math/fraction/BigFraction.html">BigFraction</a>
</li>
<li><a href="../apidocs/org/apache/commons/math/util/BigReal.html">BigReal</a>
</li>
</ul>
</p>
</div>
</div>

      </div>
    </div>
    <div class="clear">
      <hr/>
    </div>
    <div id="footer">
      <div class="xright">&#169;  
          2003-2009
    
          
  

  
    
  
  
    
  </div>
      <div class="clear">
        <hr/>
      </div>
    </div>
  </body>
</html>
